<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>How can I wrap functions which take C++ containers as arguments?</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Python">
<link rel="up" href="../faq.html" title="Chapter 5. Frequently Asked Questions (FAQs)">
<link rel="prev" href="is_return_internal_reference_eff.html" title="Is return_internal_reference efficient?">
<link rel="next" href="fatal_error_c1204_compiler_limit.html" title="fatal error C1204:Compiler limit:internal structure overflow">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="is_return_internal_reference_eff.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="fatal_error_c1204_compiler_limit.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="faq.how_can_i_wrap_functions_which_t"></a><a class="link" href="how_can_i_wrap_functions_which_t.html" title="How can I wrap functions which take C++ containers as arguments?">How can I wrap
      functions which take C++ containers as arguments?</a>
</h3></div></div></div>
<p>
        Ralf W. Grosse-Kunstleve provides these notes:
      </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p class="simpara">
            Using the regular <code class="computeroutput"><span class="identifier">class_</span><span class="special">&lt;&gt;</span></code> wrapper:
          </p>
<pre class="programlisting"><span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="string">"std_vector_double"</span><span class="special">)</span>
  <span class="special">.</span><span class="identifier">def</span><span class="special">(...)</span>
  <span class="special">...</span>
<span class="special">;</span>
</pre>
<p class="simpara">
            This can be moved to a template so that several types (<code class="computeroutput"><span class="keyword">double</span></code>, <code class="computeroutput"><span class="keyword">int</span></code>,
            <code class="computeroutput"><span class="keyword">long</span></code>, etc.) can be wrapped
            with the same code. This technique is used in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">array_family</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">flex_wrapper</span><span class="special">.</span><span class="identifier">h</span></code> in the "scitbx" package.
            The file could easily be modified for wrapping <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;&gt;</span></code> instantiations. This type of
            C++/Python binding is most suitable for containers that may contain a
            large number of elements (&gt;10000).
          </p>
</li>
<li class="listitem">
<p class="simpara">
            Using custom rvalue converters. Boost.Python "rvalue converters"
            match function signatures such as:
          </p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="keyword">const</span> <span class="special">&amp;</span><span class="identifier">array</span><span class="special">);</span> <span class="comment">// pass by const-reference</span>
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">array</span><span class="special">);</span> <span class="comment">// pass by value</span>
</pre>
<p class="simpara">
            Some custom rvalue converters are implemented in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">container_conversions</span><span class="special">.</span><span class="identifier">h</span></code> This code can be used to convert
            from C++ container types such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;&gt;</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;&gt;</span></code> to Python tuples and vice versa.
            A few simple examples can be found in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">array_family</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">regression_test_module</span><span class="special">.</span><span class="identifier">cpp</span></code>
            Automatic C++ container &lt;-&gt; Python tuple conversions are most suitable
            for containers of moderate size. These converters generate significantly
            less object code compared to alternative 1 above.
          </p>
</li>
</ol></div>
<p>
        A disadvantage of using alternative 2 is that operators such as arithmetic
        +,-,*,/,% are not available. It would be useful to have custom rvalue converters
        that convert to a "math_array" type instead of tuples. This is
        currently not implemented but is possible within the framework of Boost.Python
        V2 as it will be released in the next couple of weeks. [ed.: this was posted
        on 2002/03/10]
      </p>
<p>
        It would also be useful to also have "custom lvalue converters"
        such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;&gt;</span></code>
        &lt;-&gt; Python list. These converters would support the modification of
        the Python list from C++. For example:
      </p>
<p>
        C++:
      </p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="special">&amp;</span><span class="identifier">array</span><span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span><span class="special">=</span><span class="number">0</span><span class="special">;</span><span class="identifier">i</span><span class="special">&amp;</span><span class="identifier">lt</span><span class="special">;</span><span class="identifier">array</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span><span class="identifier">i</span><span class="special">++)</span> <span class="special">{</span>
    <span class="identifier">array</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">*=</span> <span class="number">2</span><span class="special">;</span>
  <span class="special">}</span>
<span class="special">}</span>
</pre>
<p>
        Python:
      </p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">l</span> <span class="special">=</span> <span class="special">[</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">]</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="keyword">print</span> <span class="identifier">l</span>
<span class="special">[</span><span class="number">2</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">6</span><span class="special">]</span>
</pre>
<p>
        Custom lvalue converters require changes to the Boost.Python core library
        and are currently not available.
      </p>
<p>
        P.S.:
      </p>
<p>
        The "scitbx" files referenced above are available via anonymous
        CVS:
      </p>
<pre class="programlisting"><span class="identifier">cvs</span> <span class="special">-</span><span class="identifier">d</span><span class="special">:</span><span class="identifier">pserver</span><span class="special">:</span><span class="identifier">anonymous</span><span class="error">@</span><span class="identifier">cvs</span><span class="special">.</span><span class="identifier">cctbx</span><span class="special">.</span><span class="identifier">sourceforge</span><span class="special">.</span><span class="identifier">net</span><span class="special">:/</span><span class="identifier">cvsroot</span><span class="special">/</span><span class="identifier">cctbx</span> <span class="identifier">login</span>
<span class="identifier">cvs</span> <span class="special">-</span><span class="identifier">d</span><span class="special">:</span><span class="identifier">pserver</span><span class="special">:</span><span class="identifier">anonymous</span><span class="error">@</span><span class="identifier">cvs</span><span class="special">.</span><span class="identifier">cctbx</span><span class="special">.</span><span class="identifier">sourceforge</span><span class="special">.</span><span class="identifier">net</span><span class="special">:/</span><span class="identifier">cvsroot</span><span class="special">/</span><span class="identifier">cctbx</span> <span class="identifier">co</span> <span class="identifier">scitbx</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David
      Abrahams, Stefan Seefeld<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="is_return_internal_reference_eff.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="fatal_error_c1204_compiler_limit.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
